---
title: Agentica > Tutorial > Swagger Agents
---

## Introduction

- [playground](https://stackblitz.com/~/github.com/wrtnlabs/agentica-tutorial-swagger?file=README.md) You can see the demo code on the playground.

This tutorial guides you through setting up a **fully functional Swagger Agent** using **Agentica**. With the following code block, you can create an agent that interacts with a Swagger-defined API—such as the Shopping Mall API—powered by **OpenAI's GPT model**. By providing a Swagger (OpenAPI) document, the agent automatically integrates all the API functions defined therein, and the `connection` property specifies the actual host for API requests.

## The Complete Swagger Agent

First, install the required packages:

```bash
npm install @samchon/openapi
```

Then, add the following code to your project:

```typescript
import { Agentica, assertHttpController } from "@agentica/core";
import dotenv from "dotenv";
import OpenAI from "openai";

dotenv.config();

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export const SwaggerAgent = async () =>
  new Agentica({
    model: "chatgpt",
    vendor: {
      api: openai,
      model: "gpt-4o-mini",
    },
    controllers: [
      assertHttpController({
        name: "Shopping Mall", // Name of the connector (can be any descriptive name)
        document: await fetch(
          "https://shopping-be.wrtn.ai/editor/swagger.json",
        ).then((r) => r.json()), // Swagger Document
        model: "chatgpt", // JSON schema model
        connection: {
          // This is the actual API host where the API requests will be sent.
          host: "https://shopping-be.wrtn.ai",
          headers: {
            Authorization: "Bearer *****",
          },
        },
      }),
    ],
  });
```

## Swagger API Setup

Before running your agent, ensure you have a valid OpenAPI (Swagger) document. In this example, the agent fetches a Swagger JSON from a remote URL and converts it using `OpenApi.convert`. The `connection` property specifies the host where API requests should be directed, in this case, `https://shopping-be.wrtn.ai`.

## What This Does

With this configuration, the Swagger Agent can:

- **Interact with a Swagger API:** By supplying the Swagger document, all the API functions defined in the document (for example, the Shopping Mall API functions) are automatically integrated.
- **Leverage GPT for API Interactions:** Use OpenAI's GPT model to interpret natural language queries and map them to corresponding API calls.
- **Maintain Type Safety:** Benefit from Agentica's strong typing to ensure that your API interactions are predictable and secure.
- **Streamline API Testing and Integration:** Quickly test and interact with your API using natural language, with the Swagger document serving as the source of truth for available endpoints and methods.

## Running the Agent

1. **Set Up Environment Variables:**  
   Create or update your `.env` file with the following variable:

   ```env
   OPENAI_API_KEY=your-openai-api-key
   ```

2. **Run the Code:**  
   Import and invoke `SwaggerAgent()` in your application. The agent will:
   - Fetch and convert the Swagger document.
   - Establish a connection with the API host defined in the `connection` property.
   - Allow you to interact with the API through natural language queries.

## Use Case Example

Imagine asking the agent:

> "Find all available products in the shopping mall."

The agent processes your query by matching it to the corresponding API endpoint defined in the Swagger document, sends the request to `https://shopping-be.wrtn.ai`, and then relays the API response back in a human-readable format.

## Security Note

**Warning:**  
This example is provided for demonstration purposes only. Ensure that you handle your API keys securely and do not expose them in production environments without proper security measures.
